Internet Info 1994 March

home *** CD-ROM | disk | FTP | other *** search

/ Internet Info 1994 March / Internet Info CD-ROM (Walnut Creek) (March 1994).iso / networking / terms / kermit / b / iktker.ins < prev next >

Wrap

Text File | 1993-06-29 | 21.7 KB | 445 lines

IBM System/370 MVS/TSO Kermit 4.2.n Installation Instructions (1993 June) The following instructions cover the installation of two command processors under MVS, namely, GUPI and KERMIT. GUPI could be installed for its own sake but is included here primarily because it is a tool needed in installing KERMIT. Indeed, GUPI is used for installing not only MVS/TSO Kermit, but also CICS/OS/VS Kermit. * * Installation Procedure * * 1) Get the necessary files from the Kermit distribution tape or from BITNET KERMSRV or elsewhere into your disk area. Note that many of the files are generic for Kermit-370 and may already be available to you from a local CMS site. As distributed by Columbia, the files are named as follows, all with prefix IKT or IK0 (I K Zero): IKTAUX.CMD Sample CLIST's PC, KERMAIL, etc. * IKTDYN.ASM Assembler source for DYNALC subroutine * IKTGUP.ASM Assembler source for TSO-specific part of GUPI * IKTGUP.HLP GUPI help file, TSO HELP format IKTKER.BWR A "beware" file, listing known bugs, problems, and fixes IKTKER.DOC TSO Kermit User Guide, plain text IKTKER.HLP Kermit-TSO help file, TSO HELP format * IKTKER.INS Kermit-TSO installation instructions (this file) IKTKER.UPD Updates for TSO version of Kermit-370 * IKTMAC.ASM Assembler source for TSO-specific macros IKTUTL.ASM Assembler source for TSO-specific routines IK0CMD.ASM Assembler source for command handler IK0COM.ASM Assembler source for global code IK0DEF.ASM Assembler source for parameter definitions IK0DOC.ASM Assembler source with brief history * IK0GUP.ASM Assembler source for generic update program GUPI IK0KAN.ASM Assembler source for Kanji character translation * IK0MAC.ASM Assembler source for generic Kermit macros IK0MAI.ASM Assembler source for storage initialization IK0PRO.ASM Assembler source for generic routines The files marked with asterisks are the ones necessary for installing GUPI. Those, along with the rest, are needed for KERMIT. The following files are not necessary for installation, but may be of some interest. IKCACT.ASM Assembler source for optional accounting exit routine IKTHDR.MSS Scribe source for producing IKTKER.DOC IKTKER.ANN Text of Kermit-TSO announcement for current version IKTKER.LPT Paged equivalent of IKTKER.DOC IKTKER.MSS Scribe source for TSO part of IKTKER.DOC IKTKER.PS PostScript equivalent of IKTKER.DOC IKTMVS.HLP Description of TSO-specific features IK0AAA.HLP Kermit-370 implementation notes, supported environments IK0CON.HLP Notes on supporting other terminal controllers IK0KER.ANN Text of generic Kermit-370 4.2 announcement IK0KER.MSS Scribe source for generic part of IKTKER.DOC IK0KER.UPD Update history for Kermit-370 IK0POR.HLP Notes on porting Kermit-370 to other systems IK0VER.FOR Comparison program for generating update decks 2) Allocate datasets to contain the assembled and executable code as follows. The allocation sizes here are based on "typical" disk models; each dataset should be roughly 200K in extent. You may wish to specify the primary space parameter so as to match that require- ment. However, if you wish to reuse either dataset for successive test versions or new releases, you must be sure to make a generous space allocation. Both libraries may be compressed from time to time to make "dead" storage available, but the load library will tend to grow as new releases are added. It is probably most convenient to use the following TSO commands to allocate the datasets. Note: throughout these instructions, the block size used for objects is 1680, the traditional maximum -- feel free to change it to the customary value at your site. ATTR K1OBJ RECFM(FB) LRECL(80) BLKSIZE(1680) DSORG(PO) ALLOC DSN(KERMIT.OBJ) USING(K1OBJ) SPACE(20,20) TRACKS DIR(5) ATTR K1LOD RECFM(U) BLKSIZE(6144) DSORG(PO) ALLOC DSN(KERMIT.LOAD) USING(K1LOD) SPACE(20,20) TRACKS DIR(10) The corresponding JCL is: // EXEC PGM=IEFBR14 //K1OBJ DD DCB=(RECFM=FB,LRECL=80,BLKSIZE=1680,DSORG=PO), // DSN=<user>.KERMIT.OBJ,SPACE=(TRK,(20,20,5)), // DISP=(NEW,CATLG),UNIT=whatever //K1LOD DD DCB=(RECFM=U,BLKSIZE=6144,DSORG=PO), // DSN=<user>.KERMIT.LOAD,SPACE=(TRK,(20,20,10)), // DISP=(NEW,CATLG),UNIT=whatever 3) Rename and reformat, if necessary, the source files on disk. Collect all the source files (those with extensions of ".ASM") in your disk area with names as shown above, and make sure that all have the same block size, record length, and record format. These parameters will depend on the way you obtained the files, and they need not follow the traditional pattern for assembler sources (RECFM=FB,LRECL=80). Any format compatible with QSAM is acceptable. You will also need IKTKER.UPD, and any local updates or optional updates chosen from IKTKER.BWR should also be collected into one or more files for application to the source; the JCL given below uses the name IKTKER.LCLUPD as an example for such optional updates. These files are all "raw" materials that will be combined to form the source actually supplied to the assembler. 4) Copy IKTKER.HLP into the system Help library with a member name of KERMIT so that the TSO HELP KERMIT command and Kermit-TSO's built-in HELP subcommand can find it. Similarly, copy IKTGUP.HLP into member GUPI. The most comprehensive documentation is the pair of chapters of the Kermit User Guide dealing with TSO, namely, the generic Kermit-370 chapter and the TSO-specific one. These two are bundled together in IKTKER.DOC and also in IKTKER.PS; the PostScript is suitable only for printing, but the DOC file could also be stored wherever you keep online documentation files, renamed appropriately. 5) The Generic Update Program for IBM-370 (GUPI) handles standard update information in the format found in IKTKER.UPD. Like Kermit itself, GUPI is composed of a generic part and a TSO-specific part. The former consists of IK0GUP.ASM plus parts of IK0MAC.ASM, and the latter similarly consists of IKTGUP.ASM plus parts of IKTMAC.ASM. Unlike Kermit, GUPI is both a TSO command processor and an ordinary batch program. The following batch job creates the executable program GUPI and uses it to apply the available updates to Kermit and then creates the executable load module KERMIT. Although the job is as generic as possible, there may be local variations. You must tailor the job to your site by (a) supplying an appropriate JOB card (the JOB card should insure, if necessary, a region of at least 1536K to allow execution of the assembler and GUPI), (b) changing the string "<user>" into the top-level qualifier of your disk area, (c) changing, if necessary, the name of the assembler, perhaps to IFOX00, and selecting the right DDNAME for the object output (note that MVS/XA and MVS/ESA both generally require that you use IEV90 because of petty changes in SYS1.MACLIB, but MVS/SP does not ordinarily have IEV90), (d) specifying, if necessary, a generous print limit to allow the 15,000 or more lines generated by the job, (e) changing, if necessary, the BLKSIZE of the macro library for GUPI (defined by DD statement GUPLIB.SYSUT2) to be as large as that of SYS1.MACLIB, (f) un-commenting, if necessary, the references to SYS1.AMODGEN and SYS1.MODGEN for access to the STATUS and OBTAIN macros in assembling GUPI and Kermit, (g) un-commenting, if desired, the reference to the optional local update data set for input to GUPI (in step KRMUPD) or adding any other desired update data sets to the concatenation under ddname SYSIN, (h) un-commenting, if desired, the references to the optional Kermit accounting exit routine KACCT, and (i) commenting out, if desired, the reference to IK0KAN.ASM (including it adds about 32 Kbytes to the Kermit load module). An abbreviated form of the job may be run to apply additional updates after the initial installation (simply omit job steps CNVASM through GUPLNK). You will also wish to use a new NAME for each new version of the load module. On the other hand, another abbreviated form of the job may be run for just the purpose of installing (or reinstalling) GUPI. For that, simply omit all steps after GUPLNK. //JOBLIB DD DSN=<user>.KERMIT.LOAD,DISP=OLD //* INPUT: <user>.IK*.ASM, <user>.IKTKER.UPD //* OUTPUT: <user>.KERMIT.LOAD, <user>.KERMIT.OBJ (both pre-allocated) //* //KASM PROC PRM=,USRMAC='SYS1.MACLIB',MEMBER=NULL, // USRMAC2='SYS1.MACLIB' //ASM EXEC PGM=IEV90,PARM='NORLD,NODECK,OBJECT,&PRM' //SYSIN DD DSN=&SOURCE,DISP=(OLD,PASS) //* SYSGO DD DDNAME=SYSLIN (uncomment if assembler wants SYSGO) //SYSLIB DD DSN=&USRMAC,DISP=(SHR,PASS) // DD DSN=&USRMAC2,DISP=(SHR,PASS) // DD DSN=SYS1.MACLIB,DISP=SHR //SYSLIN DD DSN=<user>.KERMIT.OBJ(&MEMBER),DISP=(OLD,PASS) //SYSPRINT DD SYSOUT=* //SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(5,2)) //SYSUT2 DD UNIT=(SYSDA,SEP=SYSUT1),SPACE=(CYL,(5,2)) //SYSUT3 DD UNIT=(SYSDA,SEP=SYSUT1),SPACE=(CYL,(5,2)) // PEND //KLINK PROC //LNK EXEC PGM=IEWL,PARM='REUS,LET' //SYSLMOD DD DSN=<user>.KERMIT.LOAD,DISP=OLD //SYSPRINT DD SYSOUT=* //SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(5,2)) // PEND //* //* ---------------- CUT HERE AFTER 1ST SUBMISSION ---------------- //* Create exit routine for IEBGENER //CNVASM EXEC KASM //SYSIN DD * UPDCNV0 START SAVE (14,12),,* USING UPDCNV0,15 LM 1,2,0(1) Get parms LH 3,82(2) LRECL LH 4,62(2) BLKSI AR 4,1 End of buffer TM 36(2),X'40' RECFM=V? BO QUIT Yes, error CVTLP CLC =C'*COPY ',0(1) BNE NOTCOPY CLC 5(48,1),6(1) BNE NOTCOPY MVC 0(12,1),=C'./ ADD NAME=' MVC 12(8,1),54(1) Copy name into ADD stmt NOTCOPY AR 1,3 Space over record CR 1,4 BL CVTLP Finish block SR 15,15 QUIT RETURN (1,12),RC=(15) END UPDCNV0 //SYSLIN DD DSN=&&UPDC,DISP=(NEW,PASS),UNIT=SYSDA,SPACE=(CYL,(1,1)), // DCB=(RECFM=FB,LRECL=80,BLKSIZE=1680) //* Link into job library //CNVLNK EXEC KLINK //SYSLIN DD DSN=&&UPDC,DISP=(OLD,DELETE) // DD * NAME UPDCNV0(R) //* Assemble DYNALC //DYNASM EXEC KASM,SOURCE='<user>.IKTDYN.ASM',MEMBER=DYNALC //* Create sequential file for GUPI macro library //GUPCPY EXEC PGM=IEBGENER //SYSIN DD * GENERATE EXITS DATA=UPDCNV0 //SYSPRINT DD DUMMY //SYSUT1 DD DSN=<user>.IK0MAC.ASM,DISP=SHR // DD DSN=<user>.IKTMAC.ASM,DISP=SHR // DD DSN=<user>.IKTGUP.ASM,DISP=SHR //SYSUT2 DD DSN=&&GUP,DISP=(NEW,PASS),UNIT=SYSDA,SPACE=(CYL,(1,1)), // DCB=(RECFM=FB,LRECL=80,BLKSIZE=2400) //* Create GUPI macro library //GUPLIB EXEC PGM=IEBUPDTE,PARM=NEW //SYSIN DD DSN=&&GUP,DISP=(OLD,DELETE) //SYSPRINT DD DUMMY //SYSUT2 DD DSN=&&GUPMAC,DISP=(NEW,PASS),UNIT=SYSDA, // SPACE=(TRK,(1,1,10),RLSE), // DCB=(RECFM=FB,LRECL=80,BLKSIZE=6160) //* Assemble and link GUPI //GUPASM EXEC KASM,SOURCE='<user>.IK0GUP.ASM',MEMBER=GUPI, // USRMAC='&&GUPMAC' //* ,USRMAC2='SYS1.MODGEN' May be needed for OBTAIN //GUPLNK EXEC KLINK //SYSLIN DD DSN=<user>.KERMIT.OBJ(GUPI),DISP=SHR // DD DSN=<user>.KERMIT.OBJ(DYNALC),DISP=SHR // DD * NAME GUPI(R) //* Assemble optional accounting exit //* ACTASM EXEC KASM,SOURCE='<user>.KACCT.ASM',MEMBER=KACCT //* ---------------------- END OF CUT ------------------------ //* //* --------------- STOP HERE IF ONLY INSTALLING GUPI ------------- //* Create updated Kermit ... //KRMUPD EXEC PGM=GUPI,REGION=1536K //SYSIN DD DSN=<user>.IKTKER.UPD,DISP=SHR //* DD DSN=<user>.IKTKER.LCLUPD,DISP=SHR Optional //SYSPRINT DD SYSOUT=* //SYSUT1 DD DSN=<user>.IK0DOC.ASM,DISP=SHR // DD DSN=<user>.IK0MAC.ASM,DISP=SHR // DD DSN=<user>.IKTMAC.ASM,DISP=SHR // DD DSN=<user>.IK0DEF.ASM,DISP=SHR // DD DSN=<user>.IK0MAI.ASM,DISP=SHR // DD DSN=<user>.IK0COM.ASM,DISP=SHR // DD DSN=<user>.IK0CMD.ASM,DISP=SHR // DD DSN=<user>.IKTUTL.ASM,DISP=SHR // DD DSN=<user>.IK0KAN.ASM,DISP=SHR Optional // DD DSN=<user>.IK0PRO.ASM,DISP=SHR //SYSUT2 DD DSN=&&UPDSRC,DISP=(NEW,PASS),SPACE=(CYL,(1,1)), // DCB=(RECFM=FB,LRECL=80,BLKSIZE=6160),UNIT=SYSDA //* //KRMASM EXEC KASM,SOURCE='&&UPDSRC',MEMBER=KERMIT,COND=(0,LT,KRMUPD) //* ,USRMAC='SYS1.AMODGEN' May be needed for STATUS //* ,USRMAC2='SYS1.MODGEN' May be needed for OBTAIN //KRMLNK EXEC KLINK,COND=((0,LT,KRMUPD),(4,LT,KRMASM.ASM)) //SYSLIN DD DSN=<user>.KERMIT.OBJ(KERMIT),DISP=SHR // DD DSN=<user>.KERMIT.OBJ(DYNALC),DISP=SHR //* DD DSN=<user>.KERMIT.OBJ(KACCT),DISP=SHR Optional // DD * ALIAS KERMIT NAME KERM420(R) // Note 1: If you prefer, you may elect to keep the source files in a PDS. If so, change the DSN references in the job accordingly. Note 2: The procedure given above assumes the availability of sources contemporaneous with this file, i.e., release 4.2 of Kermit-370. Note 3: The procedure given above preserves the sequence numbers in columns 73-80 of the source files. If you elect to use an editor to merge files, be absolutely sure that you don't inadvertently lose the original sequence numbers (something editors are prone to do). Note 4: The resulting load library KERMIT.LOAD must be placed in the link list so that the KERMIT load module will be treated as a COMMAND PROCESSOR (if not in SYS1.LINKLIST, then either concatenated to the STEPLIB for the default LOGON PROC or made known to all potential Kermit users, so that they can do the concatenation themselves). One way of testing a newly installed Kermit is to invoke it under TEST with the CP option. Note 5: The suggested scheme of naming Kermit load modules is indicated in the above job. Version 4.2.0 would be named KERM420, 4.2.1 would be KERM421, and so on. The latest version would have an alias of KERMIT. If old versions are kept indefinitely, the load library will, of course, grow. 6) Install any desired auxilliary commands from IKTAUX.CMD. These are sample CLIST's and may need to be tailored to your site. The PC command, for example, assumes that the TERMINALS macro is defined in your PC Kermit as "SERVER,CONNECT". KERMAIL and KERMPRT must be set up according to the local options and facilities for e-mail and print, respectively. 7) To run Kermit-TSO, simply type "KERMIT" to the TSO system prompt. * * Accounting Routine * * If you wish to use the optional accounting exit routine with Kermit, you must create the object for it and load it explicitly with Kermit. The sample currently available was written for CMS and must be adapted to run under MVS/TSO. Any user who does so is urged to contribute the TSO version for inclusion in the Kermit distribution under the name IKTACT.ASM. Even when such a TSO-specific sample is available, you should examine the source and customize it to your installation's needs before using it. The tailored version is assumed to be called KACCT.ASM in the relevant lines of the batch job above (currently all commented out). * * Configuration * * The IBM mainframe and its communications front end (3705, 7171, etc.) usually require that parity be used by any asynchronous ASCII device that wishes to communicate with it. Exactly which kind of parity is site-dependent. At Columbia, the 3705 requires Mark parity, and the 7171 requires Even parity. Make sure your users know to use the appropriate parity setting, as well as any other settings required for IBM mainframe communication (see p.36-39 of the Kermit book). For linemode transfers, the ASCII/EBCDIC translation in the front end is a key factor. Kermit-TSO uses an ASCII/EBCDIC translation table which conforms to the one given in the IBM System/370 Reference Summary. If your site's translation table is incompatible with the one Kermit uses, then enter the appropriate SET ATOE/ETOA/TATOE/TETOA subcommands in the system KERMINI file. As long as the system tables are invertible with respect to the printable ASCII characters (even if the A-to-E and E-to-A tables are not the inverses of each other), the SET subcommands can compensate. However, if your system's ASCII/EBCDIC tables are not invertible, Kermit will not and cannot work unless you change your system's tables. Refer to the generic Kermit-370 chapter of the User's Guide for a step-by-step customization procedure (see the section on translation tables). Kermit may also need to be configured because of a problem with VTAM for line-mode terminals -- in some versions of VTAM, there is no standard mode for transmitting the normal packet character SOH (code 1, CTRL-A), even though Kermit-TSO automatically detects the presence of VTAM and switches from TTY to VTAMTTY. A suitable substitute packet character is HT (code 9, CTRL-I). Alternatively, installing the VTAM exit routine IKTWTX1 will give local control over selection of characters to pass through to the terminal. Kermit-TSO operation is possible for most types of protocol converters; for best results, the converter should have a transparent mode. If possible, be sure the converter is configured so that the graphics or transparent mode, whatever it is called, is enabled. See IK0AAA.HLP for a list of front ends that are known to work and for a collection of notes and special warnings about some of them. Some further installation details follow for specific devices. When TSO Kermit is to be used with a 7171, make sure the 7171 is set up with its "keyboard lock delay" parameter set to 0. Otherwise, the "terminal" will hang whenever TSO Kermit clears the screen. This happens consistently when the parameter is set to 10, and not at all when set to 0. For numbers in between, the higher the number, the more it happens. There is another problem in the 7171 that can cause Kermit file transfers to abort after a flurry of retransmissions if XON/XOFF flow control is used by the receiving Kermit, or even by hardware in between the 7171 and the receiver. To prevent this problem, set the 7171 flags so that XOFF is not a valid terminator of a transparent read. See page 4-20 of "IBM 7171 Reference Manual and Programming Guide" (IBM publication number GA27-0021). Kermit operation is possible through an IBM 3708 front end in two different configurations. In the first, the terminal line must be set for either "protocol enveloping" or "dynamic" mode, and a session must be set for line-at-a-time operation for Kermit to work. Other important details of the terminal configuration are: (1) the terminal must be specified as a TWX device, (2) the SSCP format should be set to USSNTO, (3) the terminal type ID should be set to 05, (4) the line should be set for 8, or possibly 7, data bits and 1 stop bit, (5) there should be no "read prompt", and (6) the so-called "alternate" translation table (number 3) should be selected. Kermit-TSO may also need to be configured because some models of the 3708 (or some environments) do not pass the normal packet character SOH (code 1, CTRL-A). A suitable substitute is HT (code 9, CTRL-I). Alternatively, or additionally, it may help to set the 3708 "interface type" to 0. CONTROLLER must be set to TTY (or VTAMTTY if connected through TSO/VTAM without the IKTWTX1 exit), but those are the defaults. The second possible 3708 configuration is "protocol conversion" mode and makes use of the FULLSCREEN type in Kermit, which is also suitable for many other kinds of protocol converter. The basic setup consists of the following Kermit subcommands. .... mainframe ..... ....... PC ......... SET CONTROLLER FULL set send start 62 SET RECEIVE START 62 set receive start 62 SET SEND START 62 set block b SET BLOCK B set handshake none SET HANDSHAKE 0 The 62's (Greater-than sign) may be replaced by some other decimal code for a printable character. For best results, choose a character that seldom appears in the files you will be transferring. In particular, avoid the Control, Eighth-bit, and Repeat prefixes. Packet sizes are automatically restricted by Kermit-TSO, so you needn't set them unless conditions require packets shorter than the default (77). Flow control may be needed to keep up with the data rate on some equipment. The block check type should be set to "B" only if the protocol converter is overzealous in optimizing the data stream -- there are hazards in using any type other than "1" because of all the packet echoing. Refer to IK0AAA.HLP for such details. Note that the translation of characters imposes the same setup requirements on FULLSCREEN mode as on the traditional TTY or VTAMTTY modes (linemode). See the DOC. Kermit-TSO supports file transfers through the IBM 3174 AEA with B2 or higher microcode, but support is restricted to terminals with the ASCII Graphics capability in three ways that may require compensating installation: a) The terminal type must be defined in the 3174 to support graphics (only the built-in VT241 and Tektronix 4205 types plus suitable user-defined terminal types). IBM's AEA Reference describes how to set up terminal tables. b) The line must be defined without a Host Addressable Printer. c) If the 3174 is owned by VTAM, the connection must be made with a logmode that allows the Read Partition Query (such as M2SDLCQ).